IRIX Base Documentation 1998 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / mkf2c.z / mkf2c

Wrap

Text File | 1998-10-30 | 18KB | 416 lines

MMMMKKKKFFFF2222CCCC((((1111)))) MMMMKKKKFFFF2222CCCC((((1111)))) NNNNAAAAMMMMEEEE mkf2c - generate FORTRAN-C interface routines SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS mmmmkkkkffff2222cccc [ options ] [ cprog.fc [ cprog.s ] ] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _m_k_f_2_c is used to generate assembly-language routines to provide greater flexibility when calling a C function from a FORTRAN routine. _M_k_f_2_c accepts as input a set of C functions, and produces an assembly- language interface routine in the output file. If the input and output files are not specified, _m_k_f_2_c reads from _s_t_d_i_n and writes to _s_t_d_o_u_t. The input may be a copy of the actual C file being interfaced, perhaps filtered by the program _e_x_t_c_e_n_t_r_y(1). The output of _m_k_f_2_c is an assembly-language (._s) file that must be assembled with _a_s(1), and loaded with the FORTRAN and C routines that are to be interfaced. The assembly-language output is KPIC code which must be assembled with the ----KKKKPPPPIIIICCCC option to _a_s(1) unless an _u_n_s_h_a_r_e_d .o is desired. _M_k_f_2_c uses the parameter declarations in the C function headers to transform each parameter of the calling language to that of the receiving language. The standard basic C types attached to the parameters are used to determine the object each parameter represents - i.e., whether it is a value or pointer, its size, whether it is unsigned, etc. For C functions in K&R style, the opening and closing brace of the function body must be present. Information in the body of the function is ignored. For C functions in ANSI C function prototype style, the function may be either a definition (and whatever is between the opening and closing brace is ignored) or a declaration (ie, with ; rather than {}). Function parameters in ANSI C style function prototypes need not name the parameters. Function parameters in ANSI C style function prototypes cannot use typedef names to declare parameter types. _m_k_f_2_c expects its input to consist solely of the functions it is to interface, comments, and lines which begin with the preprocessor control character '#'. It can match braces, enabling it to bound function bodies. It cannot, however, understand other C constructs normally occurring at the global level (typedefs, structure declarations, data declarations, function prototypes, etc.). Such unrecognized constructs must be eliminated from the input (this is the purpose of _e_x_t_c_e_n_t_r_y(1)). _M_k_f_2_c will ignore functions of storage class _s_t_a_t_i_c . The simplest way to generate an interface for a C function is to simply hand-code a copy of the function which consists of the entry and parameter declarations with an empty body. This stub, which is traditionally suffixed with ._f_c is then used as input to _m_k_f_2_c, and the resultant ._s file is assembled and linked into the executable. The root name of the stub file must differ from the root name of the file PPPPaaaaggggeeee 1111 MMMMKKKKFFFF2222CCCC((((1111)))) MMMMKKKKFFFF2222CCCC((((1111)))) containing the actual C functions (so that the name of the resultant ._os differ). NOTE: _t_h_e -KPIC _s_w_i_t_c_h _m_u_s_t _b_e _g_i_v_e_n _t_o as(_1) _u_n_l_e_s_s _t_h_e _o_b_j_e_c_t _i_s _t_o _b_e non-shared. mkf2c foo.fc foo.s as -KPIC foo.s -o foo.o It is also possible to create wrappers from existing C source code. This is done by adding special rules to your makefile and adding special comments around each function for which an interface is to be generated. See the example at the end of this man page. The options to _m_k_f_2_c(1) are the following: ----33332222 Generate wrappers with (old) 32-bit calling conventions. At this time, it is the default, but may change as different ABIs become the future default. ----66664444 Generate wrappers with 64-bit pointer sizes, and using the 64 bit calling conventions. ----nnnn33332222 Generate wrappers with the n32 calling conventions. ----ffff Suppress extending floats to doubles across the call. Normally, formal parameters of type _f_l_o_a_t in the (K&R) C input to _m_k_f_2_c are dereferenced and converted to type _d_o_u_b_l_e across the interface, to conform to C calling conventions. This option suppresses the conversion to _d_o_u_b_l_e. If this option is selected, the receiving routine in C should have a _p_r_o_t_o_t_y_p_e with the _f_l_o_a_t parameters declared correctly. For declarations input to _m_k_f_2_c in ANSI C style function prototypes float arguments are not extended, so ----ffff need not be supplied. ----oooo _o_u_t_p_u_t Name the output file _o_u_t_p_u_t. If the output filename is not specified by a -_o _f_i_l_e_n_a_m_e switch, _m_k_f_2_c will use the second filename appearing in its argument list as the output file name. This method must be used if it is desired to generate an interface routine in a file when the input is from _s_t_d_i_n. ----UUUU Normally, upper case characters appearing in FORTRAN external names are mapped to lower case. This option suppresses that mapping, allowing FORTRAN external names to be of mixed case. This option should be used in conjunction with the -_U option to _f_7_7(_1). ----ssssiiiiggggnnnneeeedddd,,,,----uuuunnnnssssiiiiggggnnnneeeedddd Specify the _s_i_g_n_e_d attribute of single-character parameters. The setting of this option determines whether a scalar parameter of type _c_h_a_r (in the C input to _m_k_f_2_c), which corresponds to a FORTRAN argument of type _c_h_a_r_a_c_t_e_r*_1, should be sign-extended across the interface. The default setting is _u_n_s_i_g_n_e_d. PPPPaaaaggggeeee 2222 MMMMKKKKFFFF2222CCCC((((1111)))) MMMMKKKKFFFF2222CCCC((((1111)))) ----uuuu Keep underscores in function names. By default underscores are removed and a warning is issued. ----llll By default, _m_k_f_2_c truncates FORTRAN external names to _s_i_x characters to conform to the ANSI standard and to be backwards-compatible with the IRIS 4D Series. This switch allows the maximum number of characters in FORTRAN external names to be the same as that enforced by the FORTRAN front-end (currently 32). If this switch is _n_o_t specified, the FORTRAN program should have the C function name truncated to _s_i_x characters at the call. ----wwww Inhibit the generation of warning messages. As creating _w_r_a_p_p_e_r_s can cause confusion, _m_k_f_2_c gives warning messages for constructs which will result in an interface which is 'unnatural' for C (i.e., in which the C side of the interface must take special precautions when accessing the parameters or naming the routines). An example of this would be passing a FORTRAN character variable as a C character array. _M_k_f_2_c knows that this situation requires C to use special care when manipulating the string, as it is not null-terminated, and, hence, it generates a warning message. It is recommended that -_w only be used by programmers experienced with the generation of _w_r_a_p_p_e_r_s. ----ccccaaaallllllll____ssssaaaammmmeeee____ddddssssoooo This is used when the wrapper and the target C function will be placed in the same DSO. A further optimization is taken which removes the restoring of the gp register after the call return. EEEEXXXXAAAAMMMMPPPPLLLLEEEE In this example, a FORTRAN program wants to call a C function _A_l_l_P_a_r_a_m_e_t_e_r_s with many parameters. The FORTRAN program is in the file _f._f and the C function is in the file _c._c. These are the only two files in the program. The special comments /*CENTRY*/ and /*ENDCENTRY*/ have been added to the C source code to bracket the function for which an interface is to be generated. The C function header is given below: PPPPaaaaggggeeee 3333 MMMMKKKKFFFF2222CCCC((((1111)))) MMMMKKKKFFFF2222CCCC((((1111)))) /* CENTRY */ AllParameters(i,s,c,cptr,ptr1,ptr2,ar1,f,d,d1,struct1,string1,string2,u) short s; char c,*cptr; int *ptr1; char *ptr2[]; short ar1[]; float f; double d,*d1; struct test_s *struct1; char string1[],string2[30]; sometype u; { /* The C function body is ignored by _m_k_f_2_c. */ } /* ENDCENTRY */ When this function is run through _m_k_f_2_c, a complaint will be given about not understanding the type of parameter _u. It will be assumed to be a simple pointer. Additionally, a warning about passing the parameters _s_t_r_i_n_g_1 and _s_t_r_i_n_g_2 as simple pointers will be given. (These FORTRAN character variables each have an associated length which is passed as a _h_i_d_d_e_n parameter to the C function, at the end of the parameter list. These additional parameters may be accessed by the C function by the use of the _v_a_r_a_r_g_s macros. See the _F_O_R_T_R_A_N _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l for more information.) The parameter _i will be assumed to be of type _i_n_t, as it is by the C compiler _c_c_o_m during compilation. Several items are noteworthy about the parameters in this example. The parameters _i, _s, _c, _f, and _d will be dereferenced across the call. The parameter _f will be extended to a _d_o_u_b_l_e across the call unless the -_f switch is given to _m_k_f_2_c(1). The parameters _p_t_r_1, _p_t_r_2, _a_r_1, _d_1, _s_t_r_u_c_t_1, _s_t_r_i_n_g_1, and _s_t_r_i_n_g_2 will be passed as simple pointers. The FORTRAN character*1 variable which is passed as _c will be dereferenced and extended to a long across the call. If the -_s_i_g_n_e_d switch is specified, _c will be sign-extended when being dereferenced. A copy of parameter _c_p_t_r will be made and the copy null-terminated. A pointer to this copy will PPPPaaaaggggeeee 4444 MMMMKKKKFFFF2222CCCC((((1111)))) MMMMKKKKFFFF2222CCCC((((1111)))) be passed. The C entry point will be named _A_l_l_P_a_r_a_m_e_t_e_r_s. The FORTRAN entry point name depends on whether or not the -_U and/or the -_l switches have been given. The various combinations of these switches and their effect is detailed below: ___________________________ Switches FORTRAN Entry ___________________________ <_n_o_n_e> allpar_ -_l allparameters_ -_U AllPar_ -_l -_U AllParameters_ ___________________________ ||||||| ||||||| ||||||| The program can be made easily and the interface generated automatically by adding the following special rules to your makefile: # .fc must be added to your SUFFIXES between .c and .o .SUFFIXES: .SUFFIXES: .o .fc .c .s .f F2CFLAGS= ASFLAGS=-KPIC test: f.o c.o f77 -o test f.o c.o # note -- each .c file containing routines to be interfaced must have # a dependency such as the following c.o: c.fc .fc.o: cc $(CFLAGS) -c $*.c mkf2c $(F2CFLAGS) $< $*.s as $(ASFLAGS) -o $*.wo $*.s ld -r $*.o $*.wo -o $*.tmp mv $*.tmp $*.o rm -f $*.s $*.wo .c.fc: extcentry $*.c $*.fc clean: rm -f *.o test *.fc In the make, the program _e_x_t_c_e_n_t_r_y will be run on _c._c to produce _c._f_c. This program (see _e_x_t_c_e_n_t_r_y(1)) will copy to _c._f_c all text in _c._c which is between the special comments /* _C_E_N_T_R_Y */ and /* _E_N_D_C_E_N_T_R_Y */. _M_k_f_2_c PPPPaaaaggggeeee 5555 MMMMKKKKFFFF2222CCCC((((1111)))) MMMMKKKKFFFF2222CCCC((((1111)))) will then be run on _c._f_c, and the make variable _F_2_C_F_L_A_G_S will be passed to it. The C source will be compiled with _c_c(1) (using _c_c $_C_F_L_A_G_S), and the output of _m_k_f_2_c will be assembled (with _a_s $_A_S_F_L_A_G_S). These two ._os will then be loaded together into a single relocatable named _c._o. If it is desired to pass _m_k_f_2_c(1) some flags (e.g., -_l and -_s_i_g_n_e_d), the _m_a_k_e variable _F_2_C_F_L_A_G_S should be set in the makefile, as F2CFLAGS = -signed -l SSSSEEEEEEEE AAAALLLLSSSSOOOO extcentry(1), cc(1), FORTRAN Language Reference Manual DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS _M_k_f_2_c is very simple-minded about diagnosing syntax errors. It can detect such things as a formal parameter having its type declared when it is not in the formal parameter list. A few such cases give intelligible error messages. The program will complain about types it does not understand. The default type assigned in such cases is _s_i_m_p_l_e _p_o_i_n_t_e_r. _M_k_f_2_c will also delete characters from FORTRAN entry names which are illegal (e.g., underscores). The user will be warned in such instances. Most errors that the programs detect are indicated only by the source line number. If _m_k_f_2_c encounters an error which it cannot remedy, it will abort, giving the line number on which the error occurred. The resultant ._s file will be removed, and an error exit will be taken. Because of its limited error diagnostic ability, it is advisable to use _c_c (_1) to determine whether the input syntax is correct before passing it to _m_k_f_2_c. BBBBUUUUGGGGSSSS _m_k_f_2_c does not understand the ANSI notation a(void) _a_s _m_e_a_n_i_n_g _a _f_u_n_c_t_i_o_n _w_i_t_h _n_o _a_r_g_u_m_e_n_t_s. In ANSI C style function prototypes, typedef names cannot be used. AAAAUUUUTTTTHHHHOOOORRRR Greg Boyd PPPPaaaaggggeeee 6666